---
title: Component Variants
---

import { Note } from '../..'

# Component Variants

Components use custom variants to allow you to completely customize the look and feel of each component.

The following table lists each component's variant group and default variant name where applicable.

| Component    | Variant Group | Default Variant   |
| ------------ | ------------- | ----------------- |
| `Grid`       | `grids`       |
| `Button`     | `buttons`     | `primary`         |
| `Close`      | `buttons`     | `close`           |
| `IconButton` | `buttons`     | `icon`            |
| `MenuButton` | `buttons`     | `menu`            |
| `Text`       | `text`        |
| `Heading`    | `text`        | `heading`         |
| `Link`       | `links`       | `styles.a`        |
| `NavLink`    | `links`       | `nav`             |
| `Image`      | `images`      |
| `Avatar`     | `images`      | `avatar`          |
| `Card`       | `cards`       | `primary`         |
| `Container`  | `layout`      | `container`       |
| `Label`      | `forms`       | `label`           |
| `Input`      | `forms`       | `input`           |
| `Select`     | `forms`       | `select`          |
| `Textarea`   | `forms`       | `textarea`        |
| `Radio`      | `forms`       | `radio`           |
| `Checkbox`   | `forms`       | `checkbox`        |
| `Slider`     | `forms`       | `slider`          |
| `Badge`      | `badges`      |
| `Alert`      | `alerts`      |
| `Message`    | `messages`    |
| `Progress`   |               | `styles.progress` |
| `Divider`    |               | `styles.hr`       |

The following components support the `variant` prop, but do not include default variant keys.

- `Box`
- `Flex`
- `Donut`
- `Spinner`
- `Embed`
- `AspectRatio`
- `AspectImage`

<Note>

Some components reuse styles defined in `theme.styles` for default variants.

</Note>

Additional variants can be added to each group to create multiple styles for a single component.
For example, a secondary button style can be added to `theme.buttons.secondary` then applied to any Button using the `variant` prop.

```jsx
// example using a variant
<Button variant="secondary">Secondary</Button>
```

Components that don't have a dedicated variant group can reference a custom group or any existing variant using `group.variant`.

```jsx
// example using a variant for a component without a dedicated variant group
<Box variant="boxes.shout">This Box will standout!</Button>
```

## Example Theme

```js
// example theme
{
  // ...base theme...
  // After the base theme, define the variants:
  buttons: {
    secondary: {
      fontWeight: 'bold',
      color: 'white',
      bg: 'primary',
      '&:hover': {
        bg: 'dark',
      },
    },
  },
  text: {
    caps: {
      textTransform: 'uppercase',
      letterSpacing: '.2em',
    },
    heading: {
      fontFamily: 'heading',
      fontWeight: 'heading',
      lineHeight: 'heading',
    },
    display: {
      // extends the text.heading styles
      variant: 'text.heading',
      fontSize: [6, 7, 8],
      fontWeight: 'display',
    },
  },
  cards: {
    primary: {
      padding: 2,
      borderRadius: 4,
      boxShadow: '0 0 4px 1px rgba(0, 0, 0, 0.5)',
    },
  },
  boxes: {
    // Components without a dedicated variant group can reference a custom group or any existing variant using group.variant
    shout: {
      fontWeight: 'bold',
      textTransform: 'uppercase',
    },
  },
}
```
